home *** CD-ROM | disk | FTP | other *** search
/ Die Speccy' 97 / Die Speccy' 97.iso / amiga_system / the_aminet / comm / bbs / wwbbs31_source.lha / WWBBS / Programming / Config.doc next >
Text File  |  1995-07-22  |  5KB  |  168 lines
  1. Using config functions in wwbbs.library
  2. ---
  3. These functions access the stuff you can set using BBSPrefs.  There are
  4. four functions (actually eight), all of which are tag-based:
  5.  
  6.      ULONG GetConfig(struct TagItem *); - Gets configuration data
  7.      ULONG GetConfigTags(Tag,...);
  8.  
  9.      ULONG SetConfig(struct TagItem *); - Sets configuration data
  10.      ULONG SetConfigTags(Tag,...);
  11.  
  12.      BOOL AddConfig(struct TagItem *); - Adds a new config entry
  13.      BOOL AddConfigTags(Tag,...);
  14.  
  15.      BOOL RemConfig(struct TagItem *); - Removes a config entry
  16.      BOOL RemConfigTags(Tag,...);
  17.  
  18. Get and Set return the number of tags successfully processed.  Add and Rem
  19. return success or failure.
  20.  
  21. ---
  22.  
  23. There are two tags that must be present in all function calls.  They are
  24. CFGTAG_Path and CFGTAG_Name.  All of the configuration data is arranged in
  25. a heirarchal manner similar to a disk with files and directories.  The
  26. structure is as follows:
  27.  
  28.      AccessGroups/
  29.      Archivers/
  30.      Editors/
  31.      FileBases/ (*)
  32.      Menus/ (*)
  33.      MessageBases/ (*)
  34.      News/
  35.      Nodes/
  36.      Protocols/
  37.      System (this is not a directory)
  38.  
  39. In each directory exists any number of "files", which correspond to the
  40. directory they reside in.  For example, a file in the path "Protocols" may
  41. have a "file" named "Zmodem".  To access this particular file you would
  42. pass "Protocols" as the CFGTAG_Path and "Zmodem" as the CFGTAG_Name.
  43.  
  44. In the directories marked with an (*), these directories may not only
  45. contain these so-called files, but also sub-directories.  The reason for
  46. this is to allow these config items to form a tree for more functionality.
  47. For example, the directory "FileBases" can have a sub-directory in it
  48. called "Amiga", which can have a entry named "Games", so to access this
  49. particular entry you would pass "FileBases/Amiga" as the CFGTAG_Path and
  50. "Games" as the CFGTAG_Name.  Note that sub-directories can also have
  51. sub-directories.
  52.  
  53. ---
  54. Description of tags common to the four functions (but not necessarily all)
  55.  
  56.      CFGTAG_Type
  57.           This specifies the type of data that the entry (or file has), and
  58.           it also specifies which tags you are allowed to use with it to
  59.           get/set information.  The types are enumerated in wwbbs.h,
  60.           CFGTYP_*.
  61.      CFGTAG_DontSave
  62.           Set(), Add(), and Rem() automatically save the config file after
  63.           each call.  If you are performing several function calls, it
  64.           would be best to wait until you are done to perform the save.
  65.           This can be conveniently performed with the CFGTAG_ForceSave tag
  66.           and the Set() function.
  67.  
  68. ---
  69. Using Add()
  70.  
  71. You can use the following tags with Add()
  72.  
  73.      CFGTAG_Path (*)
  74.      CFGTAG_Name (*)
  75.      CFGTAG_Type (*)
  76.      CFGTAG_DontSave
  77.  
  78.           (*) required
  79.  
  80. {
  81.   AddConfigTags(
  82.     CFGTAG_Path,"FileBases",
  83.     CFGTAG_Name,"Games",
  84.     CFGTAG_Type,CFGTYP_FileBase, /* this is a UBYTE */
  85.     CFGTAG_DontSave,FALSE, /* this is a BOOL */
  86.     TAG_END);
  87. }
  88.  
  89. This function will add a config entry of the type specified by CFGTAG_Type.
  90. Note that by adding a config entry to a "file", it will turn that "file"
  91. into a directory.  For example, if you added a "file" called "Arcade" to
  92. "FileBases/Games", and if "FileBases/Games" was previously considered a
  93. file, it will now be considered a directory since it has a child entry.
  94.  
  95. ---
  96. Using Rem()
  97.  
  98. You can use the following tags with Rem():
  99.  
  100.      CFGTAG_Path (*)
  101.      CFGTAG_Name (*)
  102.      CFGTAG_DontSave
  103.  
  104.           (*) required
  105. {
  106.   RemConfigTags(
  107.     CFGTAG_Path,"FileBases"
  108.     CFGTAG_Name,"Games",
  109.     CFGTAG_DontSave,FALSE, /* this is a BOOL */
  110.     TAG_END);
  111. }
  112.  
  113. This function will remove a config entry.  You cannot remove a config entry
  114. if it has child entries (i.e. it is a directory)
  115.  
  116. ---
  117. Using Get()
  118.  
  119. In addition to the actual tags used for accessing entry-specific data, you
  120. can use the following tags with Get():
  121.  
  122.      CFGTAG_Path (*)
  123.      CFGTAG_Name (*)
  124.      CFGTAG_Type
  125.      CFGTAG_Exists - use this to find out if a entry exists
  126.      CFGTAG_Parent - use this to find out if this entry has a parent
  127.                      directory
  128.      CFGTAG_Child - use this to find out if this entry has a child entry,
  129.                     which would make it a directory
  130.      CFGTAG_GetFirst - get the name of the first entry in this directory
  131.      CFGTAG_GetLast - get the name of the last entry in this directory
  132.      CFGTAG_GetNext - get the name of the next entry in this directory
  133.      CFGTAG_GetPrevious - get the name of the previoous entry in this
  134.                           directory
  135.      CFGTAG_Next (**)
  136.      CFGTAG_NextReturn (**)
  137.  
  138.           (*) required
  139.           (**) used for special mode, explained below
  140.  
  141. {
  142.   if(GetConfigTags(
  143.        CFGTAG_Path,"MessageBases",
  144.        CFGTAG_Name,"Clone-Talk",
  145.        CFGTAG_Exists,TRUE, /* since the value that is returned is the
  146.                               number of tags processed, besides CFGTAG_Path
  147.                               and CFGTAG_Name */
  148.        TAG_END))
  149.      printf("Yes MessageBases/Clone-Talk exists\n");
  150. }
  151.  
  152. {
  153.   BOOL parent,child;
  154.   BYTE first[33],last[33],next[33],previous[33];
  155.   GetConfigTags(
  156.     CFGTAG_Path,"MessageBases",
  157.     CFGTAG_Name,"Clone-Talk",
  158.     CFGTAG_Parent,&parent,
  159.     CFGTAG_Child,&child,
  160.     CFGTAG_GetFirst,first,
  161.     CFGTAG_GetLast,last,
  162.     CFGTAG_GetNext,next,
  163.     CFGTAG_GetPrevious,previous,
  164.     TAG_END);
  165. }
  166.  
  167. /*** UNFINISHED ***/
  168.